JavaDoc

What is JavaDoc?

JavaDoc is a documentation generator that produces a searchable HTML document defining the classes and interfaces of an application. This makes it easy for you and other developers to understand the API of an application.

JavaDoc Comments

The JavaDoc tool reads through Java files and parses certain parts of the code to automatically generate useful documentation. One part of the code that will be picked up by JavaDoc is a **JavaDoc comment **(or simply doc comment).

JavaDoc comments are typically added:

• At the top of a class, right before the class name
• For each method in a class
  We'll get some practice with this when we start defining classes later in the course.

Syntax

JavaDoc comments use a simple syntax that supports multi-line HTML format documentation. Here's what the syntax looks like:

/** documentation */

And here's an example:

/** This program HelloWorld produces a standard output
 *  displaying "Hello World"
 * 
 * @author The author of the class
 * @see A reference to another class
 */

Parts of a JavaDoc Comment

Notice that JavaDoc comments are broken down into two parts:

1. The description
2. Block tags

In the above example, the description is the first part of the comment, and the block tags are the last part (@author and @see).

In this example, we have a doc comment for a method:

/**
 * This method displays a simple text output to a provided name
 * 
 *
 * @param name The name of the person we want to say “Hi” too
 * @return results Returns true if the name was printed or
 * false if it failed 
*/

Again, the first part is the description (in this case, describing the main behavior of the method), and the second part is made up of the block tags. In this case, the block tags describe the parameter of the method and what the method returns.